/**
 *  RMTransactionsFacade.java        22-ott-2009
 *   
 * Copyright (c) 2009 mentalsmash.org
 *  
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 * 
 *  http://www.apache.org/licenses/LICENSE-2.0
 * 
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * 
 *  The use of the Apache License does not indicate that this project is
 *  affiliated with the Apache Software Foundation.
 */

package org.mentalsmash.tazio.transactions.rm;

import java.io.Serializable;

import org.mentalsmash.tazio.transactions.control.TazioTransaction;
import org.mentalsmash.tazio.transactions.model.StatusResponse;
import org.mentalsmash.tazio.transactions.model.identifiers.OID;
import org.mentalsmash.tazio.transactions.model.identifiers.TID;
import org.mentalsmash.tazio.transactions.user.Share;

/**
 * The <tt>RMTransactionsFacade</tt> acts as the unique interface through which
 * a Weak Replica Manager may interact with a Replica Manager.
 * 
 * @author Andrea Reale
 * @see StatusResponse
 * @version 0.0.1
 */
public interface RMTransactionsFacade {
    /**
     * Asks the <i>Replica Manager</i> behind this Proxy to verify and commit
     * the transaction <code>transaction</code> passed as a parameter.
     * <p>
     * No guarantee is made about which <i>Replica Manager</i> of the group will
     * receive this request.
     * </p>
     * <p>
     * This method should be invoked with an <i>at most once</i> semantic, since
     * we want to avoid duplication of transaction commit requests.
     * </p>
     * 
     * @param transaction
     *            The {@Transaction object} to verify and possibly
     *            commit
     * @return The final sequence number representing the order of commitment of
     *         the transaction, if succesfull. If the transaction was rejected
     *         the return value is -1
     */
    long commitTransaction(TazioTransaction transaction);

    /**
     * Query a <i>Replica Manager</i> about the outcome of a Transaction Commit
     * Request.
     * <p>
     * Since calling this method does not alter the state of a <i>Replica
     * Manager</i> it can safely invoked with <i>at least once</i> semantics
     * </p>
     * 
     * @param tid
     *            The unique identifier of the transaction whose status is to
     *            enquiry.
     * @return
     */
    StatusResponse whatAboutThisTx(TID tid);

    /**
     * Retrieves the ROOT object, i.e a Proxy for the RM-side
     * {@link TransactionalObjectsShare} containing copies of the system's
     * transactional objects
     */
    Share getShare();

    /**
     * Retrieves the initial sequence number for a local transaction to begin.
     * That sequence number is the number of the last committed transaction seen
     * by the Replica Manager
     * <p>
     * Since calling this method does not alter the state of a <i>Replica
     * Manager</i> it can safely invoked with <i>at least once</i> semantics
     * </p>
     * 
     * @return the initial sequence number for a transaction to begin
     */
    long beginTransaction();

    <T extends Serializable> T createObject(Class<T> txInterface);

    boolean removeFromRootSet(OID objectId);

}
